Apple, the Apple logo, AppleScript, Bento, Macintosh, QuickTime, and OpenDoc are
registered trademarks of Apple Computer, Inc.
Finder, Mac, and QuickDraw are trademarks of Apple Computer, Inc.
SOM, SOMObjects, and System Object Model are licensed trademarks of IBM Corporation.
Introduction
Frames have a link status that indicates the frame's participation in links maintained by containing parts. All OpenDoc parts that support embedding are responsible for ensuring that the link status of their embedded frames is set correctly. This document summarizes the part responsibilities for a part that does not support linking. Developers of parts supporting linking are referred to the Linking recipes for more information.
Implementing LinkStatusChanged
All parts that support embedding must implement ODPart::LinkStatusChanged. All they must do is pass the notification along to all embedded frames by calling ODFrame::ChangeLinkStatus. It is not necessary to internalize an embedded frame to make this call; it can be postponed until the embedded frame is internalized for some other reason.
(Newly documented for DR5)
If the frame passed to LinkStatusChanged has been opened into a window, the displayed part should call the ChangeLinkStatus method of the root frame of the window. This ensures that all frames in the window have their link status set correctly. (Its not sufficient to call ChangeLinkStatus on only the frames embedded in that root frame!) Note that if a part calls the ChangeLinkStatus method of one of its display frames, the part's own LinkStatusChanged method will be called (in this case, recursively).
Internalizing an Embedded Frame
It is the responsibility of every part to ensure that the link status of their embedded frames is set correctly. The easiest way for a part editor that does not support linking to do this is to call the frame's ChangeLinkStatus method immediately after internalizing the embedded frame. Editors that don't support linking can specify the link status constant kODNotInLink; ChangeLinkStatus will take the containing frame's link status into account in determining the link status value actually set. For example:
Note: Parts that support linking must not specify the link status constant kODNotInLink if the frame is embedded within a link source or destination maintained by the part. See the Linking recipes for more information on the link status value to use.
Embedding a Frame
Parts must set the link status of frames they embed, be it by a paste, drop, or some other means. If the part does not support linking, it should call the frame's ChangeLinkStatus method immediately after the frame is embedded and internalized.
Determining the Link Status of a Display Frame
(Newly documented for DR5)
Before your editor allows modification of a part's content, it must determine the link status of the frame in which it is being modified. Your editor should be careful not to assume a display frame's link status is kODNotInLink; LinkStatusChanged won't be called when a display frame is reconnected unless the frame's link status has changed. If your part caches the link status of its display frames, initialize the cached setting by calling GetLinkStatus on the frame when it is added or reconnected.
If the user attempts to modify part content in a frame with a link status of kODInLinkDestination, your editor should call the EditInLink method of the display frame. Follow the steps described in the OpenDoc Programmer's Guide.
